<?php
/**
 *+------------------
 * Lflow
 *+------------------
 * Copyright (c) 2023~2030 gitee.com/liu_guan_qing All rights reserved.本版权不可删除，侵权必究
 *+------------------
 * Author: Mr.April(405784684@qq.com)
 *+------------------
 */
declare (strict_types=1);

namespace lflow;

use lflow\entity\HistoryTask;
use lflow\entity\Task;
use lflow\model\CustomModel;
use lflow\model\ProcessModel;
use lflow\model\TaskModel;
use lflow\workflow\Execution;

/**
 * 任务业务类，包括以下服务：
 * 1、创建任务
 * 2、添加、删除参与者
 * 3、完成任务
 * 4、撤回任务
 * 5、回退任务
 * 6、提取任务
 *
 * @author Mr.April
 * @since  1.0
 */
interface ITaskService
{
    /**
     * complete
     *
     * @param string      $taskId   任务id
     * @param string|null $operator 操作人
     * @param null        $args     参数集合
     *
     * @return \lflow\entity\Task
     */
    public function complete(string $taskId, string $operator = null, $args = null): Task;

    /**
     * updateTask  更新任务对象
     *
     * @param \lflow\entity\Task $task
     */
    public function updateTask(Task $task): void;

    /**
     * history  根据执行对象、自定义节点模型创建历史任务记录
     *
     * @param \lflow\workflow\Execution $execution
     * @param \lflow\model\CustomModel  $model
     *
     * @return \lflow\entity\HistoryTask
     */
    public function history(Execution $execution, CustomModel $model): HistoryTask;

    /**
     * take  根据任务主键ID，操作人ID提取任务 提取任务相当于预受理操作，仅仅标识此任务只能由此操作人处理
     *
     * @param string $taskId   任务id
     * @param string $operator 操作人id
     *
     * @return \lflow\entity\Task
     */
    public function take(string $taskId, string $operator): Task;

    /**
     * resume  根据历史任务主键id，操作人唤醒历史任务 该方法会导致流程状态不可控，请慎用
     *
     * @param string $taskId
     * @param string $operator
     *
     * @return \lflow\entity\Task
     */
    public function resume(string $taskId, string $operator): Task;

    /**
     * addTaskActor  向指定的任务id添加参与者
     *
     * @param string $taskId      任务id
     * @param int    $performType 参与类型
     * @param string $actors      参与者
     */
    public function addTaskActor(string $taskId, int $performType, string $actors): void;

    /**
     * removeTaskActor  对指定的任务id删除参与者
     *
     * @param string $taskId 任务id
     * @param string $actors 参与者
     */
    public function removeTaskActor(string $taskId, string $actors): void;

    /**
     * withdrawTask  根据任务主键id、操作人撤回任务
     *
     * @param string $taskId   任务id
     * @param string $operator 操作人
     *
     * @return \lflow\entity\Task
     */
    public function withdrawTask(string $taskId, string $operator): Task;

    /**
     * rejectTask  根据当前任务对象驳回至上一步处理
     *
     * @param \lflow\model\ProcessModel $model       流程定义模型，用以获取上一步模型对象
     * @param \lflow\entity\Task        $currentTask 当前任务对象
     *
     * @return \lflow\entity\Task
     */
    public function rejectTask(ProcessModel $model, Task $currentTask): Task;

    /**
     * isAllowed  根据taskId、operator，判断操作人operator是否允许执行任务
     *
     * @param \lflow\entity\Task $task
     * @param string             $operator
     *
     * @return bool
     */
    public function isAllowed(Task $task, string $operator): bool;

    /**
     * createTask  根据任务模型、执行对象创建新的任务
     *
     * @param \lflow\model\TaskModel    $taskModel 任务模型
     * @param \lflow\workflow\Execution $execution 执行对象
     *
     * @return array
     */
    public function createTask(TaskModel $taskModel, Execution $execution): array;

    /**
     * createNewTask  根据已有任务id、任务类型、参与者创建新的任务
     *
     * @param string $taskId   主办任务id
     * @param int    $taskType 任务类型
     * @param string $actors   参与者集合
     *
     * @return array
     */
    public function createNewTask(string $taskId, int $taskType, string $actors): array;

    /**
     * getTaskModel  根据任务id获取任务模型
     *
     * @param string $taskId 任务id
     *
     * @return \lflow\model\TaskModel
     */
    public function getTaskModel(string $taskId): TaskModel;
}